<!doctype html>

<html>
<head>
  <link rel="shortcut icon" href="static/images/favicon.ico" type="image/x-icon">
  <title>math.js (Closure Library API Documentation - JavaScript)</title>
  <link rel="stylesheet" href="static/css/base.css">
  <link rel="stylesheet" href="static/css/doc.css">
  <link rel="stylesheet" href="static/css/sidetree.css">
  <link rel="stylesheet" href="static/css/prettify.css">

  <script>
     var _staticFilePath = "static/";
  </script>

  <script src="static/js/doc.js">
  </script>

  <meta charset="utf8">
</head>

<body onload="prettyPrint()">

<div id="header">
  <div class="g-section g-tpl-50-50 g-split">
    <div class="g-unit g-first">
      <a id="logo" href="index.html">Closure Library API Documentation</a>
    </div>

    <div class="g-unit">
      <div class="g-c">
        <strong>Go to class or file:</strong>
        <input type="text" id="ac">
      </div>
    </div>
  </div>
</div>

<div class="clear"></div>

<h2><a href="closure_goog_math_math.js.html">math.js</a></h2>

<pre class="prettyprint lang-js">
<a name="line1"></a>// Licensed under the Apache License, Version 2.0 (the &quot;License&quot;);
<a name="line2"></a>// you may not use this file except in compliance with the License.
<a name="line3"></a>// You may obtain a copy of the License at
<a name="line4"></a>//
<a name="line5"></a>//     http://www.apache.org/licenses/LICENSE-2.0
<a name="line6"></a>//
<a name="line7"></a>// Unless required by applicable law or agreed to in writing, software
<a name="line8"></a>// distributed under the License is distributed on an &quot;AS IS&quot; BASIS,
<a name="line9"></a>// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
<a name="line10"></a>// See the License for the specific language governing permissions and
<a name="line11"></a>// limitations under the License.
<a name="line12"></a>
<a name="line13"></a>// Copyright 2006 Google Inc. All Rights Reserved.
<a name="line14"></a>
<a name="line15"></a>/**
<a name="line16"></a> * @fileoverview Additional mathematical functions.
<a name="line17"></a> */
<a name="line18"></a>
<a name="line19"></a>
<a name="line20"></a>goog.provide(&#39;goog.math&#39;);
<a name="line21"></a>
<a name="line22"></a>
<a name="line23"></a>goog.require(&#39;goog.array&#39;);
<a name="line24"></a>// TODO: Remove this require once all dependant files require the
<a name="line25"></a>// correct subclasses instead of just goog.math.
<a name="line26"></a>goog.require(&#39;goog.math.Box&#39;);
<a name="line27"></a>goog.require(&#39;goog.math.Coordinate&#39;);
<a name="line28"></a>goog.require(&#39;goog.math.Range&#39;);
<a name="line29"></a>goog.require(&#39;goog.math.Rect&#39;);
<a name="line30"></a>goog.require(&#39;goog.math.Size&#39;);
<a name="line31"></a>
<a name="line32"></a>
<a name="line33"></a>/**
<a name="line34"></a> * Returns a random integer greater than or equal to 0 and less than {@code a}.
<a name="line35"></a> * @param {number} a  The upper bound for the random integer (exclusive).
<a name="line36"></a> * @return {number} A random integer N such that 0 &lt;= N &lt; a.
<a name="line37"></a> */
<a name="line38"></a>goog.math.randomInt = function(a) {
<a name="line39"></a>  return Math.floor(Math.random() * a);
<a name="line40"></a>};
<a name="line41"></a>
<a name="line42"></a>
<a name="line43"></a>/**
<a name="line44"></a> * Returns a random number greater than or equal to {@code a} and less than
<a name="line45"></a> * {@code b}.
<a name="line46"></a> * @param {number} a  The lower bound for the random number (inclusive).
<a name="line47"></a> * @param {number} b  The upper bound for the random number (exclusive).
<a name="line48"></a> * @return {number} A random number N such that a &lt;= N &lt; b.
<a name="line49"></a> */
<a name="line50"></a>goog.math.uniformRandom = function(a, b) {
<a name="line51"></a>  return a + Math.random() * (b - a);
<a name="line52"></a>};
<a name="line53"></a>
<a name="line54"></a>
<a name="line55"></a>/**
<a name="line56"></a> * Takes a number and clamps it to within the provided bounds.
<a name="line57"></a> * @param {number} value The input number.
<a name="line58"></a> * @param {number} min The minimum value to return.
<a name="line59"></a> * @param {number} max The maximum value to return.
<a name="line60"></a> * @return {number} The input number if it is within bounds, or the nearest
<a name="line61"></a> *     number within the bounds.
<a name="line62"></a> */
<a name="line63"></a>goog.math.clamp = function(value, min, max) {
<a name="line64"></a>  return Math.min(Math.max(value, min), max);
<a name="line65"></a>};
<a name="line66"></a>
<a name="line67"></a>
<a name="line68"></a>/**
<a name="line69"></a> * The % operator in JavaScript returns the remainder of a / b, but differs from
<a name="line70"></a> * some other languages in that the result will have the same sign as the
<a name="line71"></a> * dividend. For example, -1 % 8 == -1, whereas in some other languages
<a name="line72"></a> * (such as Python) the result would be 7. This function emulates the more
<a name="line73"></a> * correct modulo behavior, which is useful for certain applications such as
<a name="line74"></a> * calculating an offset index in a circular list.
<a name="line75"></a> *
<a name="line76"></a> * @param {number} a The dividend.
<a name="line77"></a> * @param {number} b The divisor.
<a name="line78"></a> * @return {number} a % b where the result is between 0 and b (either 0 &lt;= x &lt; b
<a name="line79"></a> *     or b &lt; x &lt;= 0, depending on the sign of b).
<a name="line80"></a> */
<a name="line81"></a>goog.math.modulo = function(a, b) {
<a name="line82"></a>  var r = a % b;
<a name="line83"></a>  // If r and b differ in sign, add b to wrap the result to the correct sign.
<a name="line84"></a>  return (r * b &lt; 0) ? r + b : r;
<a name="line85"></a>};
<a name="line86"></a>
<a name="line87"></a>
<a name="line88"></a>/**
<a name="line89"></a> * Performs linear interpolation between values a and b. Returns the value
<a name="line90"></a> * between a and b proportional to x (when x is between 0 and 1. When x is
<a name="line91"></a> * outside this range, the return value is a linear extrapolation).
<a name="line92"></a> * @param {number} a A number.
<a name="line93"></a> * @param {number} b A number.
<a name="line94"></a> * @param {number} x The proportion between a and b.
<a name="line95"></a> * @return {number} The interpolated value between a and b.
<a name="line96"></a> */
<a name="line97"></a>goog.math.lerp = function(a, b, x) {
<a name="line98"></a>  return a + x * (b - a);
<a name="line99"></a>};
<a name="line100"></a>
<a name="line101"></a>
<a name="line102"></a>/**
<a name="line103"></a> * Tests whether the two values are equal to each other, within a certain
<a name="line104"></a> * tolerance to adjust for floating pount errors.
<a name="line105"></a> * @param {number} a A number.
<a name="line106"></a> * @param {number} b A number.
<a name="line107"></a> * @param {number} opt_tolerance Optional tolerance range. Defaults to 0.000001.
<a name="line108"></a> *     If specified, should be greater than 0.
<a name="line109"></a> * @return {boolean} Whether {@code a} and {@code b} are nearly equal.
<a name="line110"></a> */
<a name="line111"></a>goog.math.nearlyEquals = function(a, b, opt_tolerance) {
<a name="line112"></a>  return Math.abs(a - b) &lt;= (opt_tolerance || 0.000001);
<a name="line113"></a>};
<a name="line114"></a>
<a name="line115"></a>
<a name="line116"></a>/**
<a name="line117"></a> * Standardizes an angle to be in range [0-360). Negative angles become
<a name="line118"></a> * positive, and values greater than 360 are returned modulo 360.
<a name="line119"></a> * @param {number} angle Angle in degrees.
<a name="line120"></a> * @return {number} Standardized angle.
<a name="line121"></a> */
<a name="line122"></a>goog.math.standardAngle = function(angle) {
<a name="line123"></a>  return goog.math.modulo(angle, 360);
<a name="line124"></a>};
<a name="line125"></a>
<a name="line126"></a>
<a name="line127"></a>/**
<a name="line128"></a> * Converts degrees to radians.
<a name="line129"></a> * @param {number} angleDegrees Angle in degrees.
<a name="line130"></a> * @return {number} Angle in radians.
<a name="line131"></a> */
<a name="line132"></a>goog.math.toRadians = function(angleDegrees) {
<a name="line133"></a>  return angleDegrees * Math.PI / 180;
<a name="line134"></a>};
<a name="line135"></a>
<a name="line136"></a>
<a name="line137"></a>/**
<a name="line138"></a> * Converts radians to degrees.
<a name="line139"></a> * @param {number} angleRadians Angle in radians.
<a name="line140"></a> * @return {number} Angle in degrees.
<a name="line141"></a> */
<a name="line142"></a>goog.math.toDegrees = function(angleRadians) {
<a name="line143"></a>  return angleRadians * 180 / Math.PI;
<a name="line144"></a>};
<a name="line145"></a>
<a name="line146"></a>
<a name="line147"></a>/**
<a name="line148"></a> * For a given angle and radius, finds the X portion of the offset.
<a name="line149"></a> * @param {number} degrees Angle in degrees (zero points in +X direction).
<a name="line150"></a> * @param {number} radius Radius.
<a name="line151"></a> * @return {number} The x-distance for the angle and radius.
<a name="line152"></a> */
<a name="line153"></a>goog.math.angleDx = function(degrees, radius) {
<a name="line154"></a>  return radius * Math.cos(goog.math.toRadians(degrees));
<a name="line155"></a>};
<a name="line156"></a>
<a name="line157"></a>
<a name="line158"></a>/**
<a name="line159"></a> * For a given angle and radius, finds the Y portion of the offset.
<a name="line160"></a> * @param {number} degrees Angle in degrees (zero points in +X direction).
<a name="line161"></a> * @param {number} radius Radius.
<a name="line162"></a> * @return {number} The y-distance for the angle and radius.
<a name="line163"></a> */
<a name="line164"></a>goog.math.angleDy = function(degrees, radius) {
<a name="line165"></a>  return radius * Math.sin(goog.math.toRadians(degrees));
<a name="line166"></a>};
<a name="line167"></a>
<a name="line168"></a>
<a name="line169"></a>/**
<a name="line170"></a> * Computes the angle between two points (x1,y1) and (x2,y2).
<a name="line171"></a> * Angle zero points in the +X direction, 90 degrees points in the +Y
<a name="line172"></a> * direction (down) and from there we grow clockwise towards 360 degrees.
<a name="line173"></a> * @param {number} x1 x of first point.
<a name="line174"></a> * @param {number} y1 y of first point.
<a name="line175"></a> * @param {number} x2 x of second point.
<a name="line176"></a> * @param {number} y2 y of second point.
<a name="line177"></a> * @return {number} Standardized angle in degrees of the vector from
<a name="line178"></a> *     x1,y1 to x2,y2.
<a name="line179"></a> */
<a name="line180"></a>goog.math.angle = function(x1, y1, x2, y2) {
<a name="line181"></a>  return goog.math.standardAngle(goog.math.toDegrees(Math.atan2(y2 - y1,
<a name="line182"></a>                                                                x2 - x1)));
<a name="line183"></a>};
<a name="line184"></a>
<a name="line185"></a>
<a name="line186"></a>/**
<a name="line187"></a> * Computes the difference between startAngle and endAngle (angles in degrees).
<a name="line188"></a> * @param {number} startAngle  Start angle in degrees.
<a name="line189"></a> * @param {number} endAngle  End angle in degrees.
<a name="line190"></a> * @return {number} The number of degrees that when added to
<a name="line191"></a> *     startAngle will result in endAngle. Positive numbers mean that the
<a name="line192"></a> *     direction is clockwise. Negative numbers indicate a counter-clockwise
<a name="line193"></a> *     direction.
<a name="line194"></a> *     The shortest route (clockwise vs counter-clockwise) between the angles
<a name="line195"></a> *     is used.
<a name="line196"></a> *     When the difference is 180 degrees, the function returns 180 (not -180)
<a name="line197"></a> *     angleDifference(30, 40) is 10, and angleDifference(40, 30) is -10.
<a name="line198"></a> *     angleDifference(350, 10) is 20, and angleDifference(10, 350) is -20.
<a name="line199"></a> */
<a name="line200"></a>goog.math.angleDifference = function(startAngle, endAngle) {
<a name="line201"></a>  var d = goog.math.standardAngle(endAngle) -
<a name="line202"></a>          goog.math.standardAngle(startAngle);
<a name="line203"></a>  if (d &gt; 180) {
<a name="line204"></a>    d = d - 360;
<a name="line205"></a>  } else if (d &lt;= -180) {
<a name="line206"></a>    d = 360 + d;
<a name="line207"></a>  }
<a name="line208"></a>  return d;
<a name="line209"></a>};
<a name="line210"></a>
<a name="line211"></a>
<a name="line212"></a>/**
<a name="line213"></a> * Returns the sign of a number as per the &quot;sign&quot; or &quot;signum&quot; function.
<a name="line214"></a> * @param {number} x The number to take the sign of.
<a name="line215"></a> * @return {number} -1 when negative, 1 when positive, 0 when 0.
<a name="line216"></a> */
<a name="line217"></a>goog.math.sign = function(x) {
<a name="line218"></a>  return x == 0 ? 0 : (x &lt; 0 ? -1 : 1);
<a name="line219"></a>};
<a name="line220"></a>
<a name="line221"></a>
<a name="line222"></a>/**
<a name="line223"></a> * JavaScript implementation of Longest Common Subsequence problem.
<a name="line224"></a> * http://en.wikipedia.org/wiki/Longest_common_subsequence
<a name="line225"></a> *
<a name="line226"></a> * Returns the longest possible array that is subarray of both of given arrays.
<a name="line227"></a> *
<a name="line228"></a> * @param {Array.&lt;Object&gt;} array1 First array of objects.
<a name="line229"></a> * @param {Array.&lt;Object&gt;} array2 Second array of objects.
<a name="line230"></a> * @param {Function} opt_compareFn Function that acts as a custom comparator
<a name="line231"></a> *     for the array ojects. Function should return true if objects are equal,
<a name="line232"></a> *     otherwise false.
<a name="line233"></a> * @param {Function} opt_collectorFn Function used to decide what to return
<a name="line234"></a> *     as a result subsequence. It accepts 2 arguments: index of common element
<a name="line235"></a> *     in the first array and index in the second. The default function returns
<a name="line236"></a> *     element from the first array.
<a name="line237"></a> * @return {Array.&lt;Object&gt;} A list of objects that are common to both arrays
<a name="line238"></a> *     such that there is no common subsequence with size greater than the
<a name="line239"></a> *     length of the list.
<a name="line240"></a> */
<a name="line241"></a>goog.math.longestCommonSubsequence = function(
<a name="line242"></a>    array1, array2, opt_compareFn, opt_collectorFn) {
<a name="line243"></a>
<a name="line244"></a>  var compare = opt_compareFn || function(a, b) {
<a name="line245"></a>    return a == b;
<a name="line246"></a>  };
<a name="line247"></a>
<a name="line248"></a>  var collect = opt_collectorFn || function(i1, i2) {
<a name="line249"></a>    return array1[i1];
<a name="line250"></a>  };
<a name="line251"></a>
<a name="line252"></a>  var length1 = array1.length;
<a name="line253"></a>  var length2 = array2.length;
<a name="line254"></a>
<a name="line255"></a>  var arr = [];
<a name="line256"></a>  for (var i = 0; i &lt; length1 + 1; i++) {
<a name="line257"></a>    arr[i] = [];
<a name="line258"></a>    arr[i][0] = 0;
<a name="line259"></a>  }
<a name="line260"></a>
<a name="line261"></a>  for (var j = 0; j &lt; length2 + 1; j++) {
<a name="line262"></a>    arr[0][j] = 0;
<a name="line263"></a>  }
<a name="line264"></a>
<a name="line265"></a>  for (i = 1; i &lt;= length1; i++) {
<a name="line266"></a>    for (j = 1; j &lt;= length1; j++) {
<a name="line267"></a>      if (compare(array1[i - 1], array2[j - 1])) {
<a name="line268"></a>        arr[i][j] = arr[i - 1][j - 1] + 1;
<a name="line269"></a>      } else {
<a name="line270"></a>        arr[i][j] = Math.max(arr[i - 1][j], arr[i][j - 1]);
<a name="line271"></a>      }
<a name="line272"></a>    }
<a name="line273"></a>  }
<a name="line274"></a>
<a name="line275"></a>  // Backtracking
<a name="line276"></a>  var result = [];
<a name="line277"></a>  var i = length1, j = length2;
<a name="line278"></a>  while (i &gt; 0 &amp;&amp; j &gt; 0) {
<a name="line279"></a>    if (compare(array1[i - 1], array2[j - 1])) {
<a name="line280"></a>      result.unshift(collect(i - 1, j - 1));
<a name="line281"></a>      i--;
<a name="line282"></a>      j--;
<a name="line283"></a>    } else {
<a name="line284"></a>      if (arr[i - 1][j] &gt; arr[i][j - 1]) {
<a name="line285"></a>        i--;
<a name="line286"></a>      } else {
<a name="line287"></a>        j--;
<a name="line288"></a>      }
<a name="line289"></a>    }
<a name="line290"></a>  }
<a name="line291"></a>
<a name="line292"></a>  return result;
<a name="line293"></a>};
<a name="line294"></a>
<a name="line295"></a>
<a name="line296"></a>/**
<a name="line297"></a> * Returns the sum of the arguments.
<a name="line298"></a> * @param {number} var_args Numbers to add.
<a name="line299"></a> * @return {number} The sum of the arguments (0 if no arguments were provided,
<a name="line300"></a> *     {@code NaN} if any of the arguments is not a valid number).
<a name="line301"></a> */
<a name="line302"></a>goog.math.sum = function(var_args) {
<a name="line303"></a>  return /** @type {number} */ (goog.array.reduce(arguments,
<a name="line304"></a>      function(sum, value) {
<a name="line305"></a>    return sum + value;
<a name="line306"></a>  }, 0));
<a name="line307"></a>};
<a name="line308"></a>
<a name="line309"></a>
<a name="line310"></a>/**
<a name="line311"></a> * Returns the arithmetic mean of the arguments.
<a name="line312"></a> * @param {number} var_args Numbers to average.
<a name="line313"></a> * @return {number} The average of the arguments ({@code NaN} if no arguments
<a name="line314"></a> *     were provided or any of the arguments is not a valid number).
<a name="line315"></a> */
<a name="line316"></a>goog.math.average = function(var_args) {
<a name="line317"></a>  return goog.math.sum.apply(null, arguments) / arguments.length;
<a name="line318"></a>};
<a name="line319"></a>
<a name="line320"></a>
<a name="line321"></a>/**
<a name="line322"></a> * Returns the sample standard deviation of the arguments.  For a definition of
<a name="line323"></a> * sample standard deviation, see e.g.
<a name="line324"></a> * http://en.wikipedia.org/wiki/Standard_deviation
<a name="line325"></a> * @param {number} var_args Number samples to analyze.
<a name="line326"></a> * @return {number} The sample standard deviation of the arguments (0 if fewer
<a name="line327"></a> *     than two samples were provided, or {@code NaN} if any of the samples is
<a name="line328"></a> *     not a valid number).
<a name="line329"></a> */
<a name="line330"></a>goog.math.standardDeviation = function(var_args) {
<a name="line331"></a>  var sampleSize = arguments.length;
<a name="line332"></a>  if (sampleSize &lt; 2) {
<a name="line333"></a>    return 0;
<a name="line334"></a>  }
<a name="line335"></a>
<a name="line336"></a>  var mean = goog.math.average.apply(null, arguments);
<a name="line337"></a>  var variance = goog.math.sum.apply(null, goog.array.map(arguments,
<a name="line338"></a>      function(val) {
<a name="line339"></a>        return Math.pow(val - mean, 2);
<a name="line340"></a>      })) / (sampleSize - 1);
<a name="line341"></a>
<a name="line342"></a>  return Math.sqrt(variance);
<a name="line343"></a>};
<a name="line344"></a>
<a name="line345"></a>
<a name="line346"></a>/**
<a name="line347"></a> * Returns whether the supplied number represents an integer, i.e. that is has
<a name="line348"></a> * no fractional component.  No range-checking is performed on the number.
<a name="line349"></a> * @param {number} num The number to test.
<a name="line350"></a> * @return {boolean} Whether {@code num} is an integer.
<a name="line351"></a> */
<a name="line352"></a>goog.math.isInt = function(num) {
<a name="line353"></a>  return isFinite(num) &amp;&amp; num % 1 == 0;
<a name="line354"></a>};
<a name="line355"></a>
<a name="line356"></a>
<a name="line357"></a>/**
<a name="line358"></a> * Returns whether the supplied number is finite and not NaN.
<a name="line359"></a> * @param {number} num The number to test.
<a name="line360"></a> * @return {boolean} Whether {@code num} is a finite number.
<a name="line361"></a> */
<a name="line362"></a>goog.math.isFiniteNumber = function(num) {
<a name="line363"></a>  return isFinite(num) &amp;&amp; !isNaN(num);
<a name="line364"></a>};
</pre>


</body>
</html>
